<html>
<head>
<title>Jsponic</title>
<style>
	body { font-family:Verdana, Geneva, Arial, Helvetica, sans-serif;}
</style>
</head>
<body>
<h1>Jsponic</h1>
<p>
Jsponic is a server that implements the JSPON protocol for exposing persistent data storage as 
RESTful JSON web services, and with full capabilities for modification of persisted data, execution of remote/distributed
JavaScript methods, and data centric object level security. 
</p>
<h2>Requirements</h2>
<p>
JDK 1.5</p>
<h2>Installation</h2>
<p>
If you have downloaded Jsponic with Tomcat follow these steps:
<ol>
<li>Unzip the downloaded file
</li>
<li>Ensure that your JAVA_HOME environment variable is set to the base of your JDK directory</li>
<li>Go to the bin directory and run the startup script. See the 
<a href="http://tomcat.apache.org/tomcat-6.0-doc/setup.html">Tomcat setup page</a> for more information.</li>
</ol>
If you have downloaded the Jsponic web application (without Tomcat), follow these steps:
<ol><li>Ensure that you have a web application server setup (such as Tomcat)</li>
<li>If you have an existing web application, save a copy of your web.xml file</li>
<li>Unzip the downloaded file into your desired web application directory</li>
<li>Merge the filter and servlet configurations in the new Jsponic web.xml file into your old web.xml file and put
it your WEB-INF directory</li>
</ol>
</p>
<h2>Using Jsponic</h2>
<p>Jsponic is a backend server for JSPON clients. You can use the included <a href="browser.html?id=root">JSPON Object browser (browser.html)</a>
to browse and modify persisted data in the Jsponic server. You can use the included 
<a href="persevere-readme.html">Persevere JavaScript framework</a>
to build JavaScript based applications that utilize the persisted data on the Jsponic server.
<a href="examples-pjs.html">Examples of Persevere/Jsponic applications</a> are included in the root directory. 
Jsponic supports execution of JavaScript on the server providing access to the same
persistent data exposed to clients using persistent object mapping, which provides 
for client/server distributing computing capabilities.
Jsponic implements the <a href="http://www.persistentjavascript.org">Persistent JavaScript API</a>
to access persisted data. 
<a href="examples-persisted.html">Here is an example</a> and <a href="browser.html?id=root.examples">the persisted application code (under customersApp)</a> of distributed 
computing/remote method calls between the client and server.
</p>
<h3>Setting up Security</h3>
<p>
When Jsponic is first setup, there are no users in the system and so it does not enforce any security. When
the first user is created, this user is setup to be the super user for the system, and from then on, all secured
access will require a login. This simplest way to create a user is with the <a href="browser.html?id=root">JSPON Object browser</a>.
From the browser, click on sign in, and you can create a new user. Once this user is created, only this user can
modify data, and all data will be readonly for all other users. You can modify
the access levels for different objects, and add new users to groups to allow access for modification of data.
</p>
<h3>Defining Object Access Levels in the default Object Database</h3>
<p>
Every data source can define their own security using the DataSource API. However, the default object database in Jsponic
provides an easy, configurable way to define security without writing code.  
The access levels for objects are defined with Access Control Lists (ACL). Every object that has an explicitly defined
ACL has it's access level determined by the ACL. If an object does not have an explicit ACL, it will inherit
the access level from the object that references it (if there are multiple references to an object, it inherits
from the first object that referenced it). To define an ACL with the <a href="browser.html?id=root">JSPON Object 
browser</a>, choose an object and click the "Add an Acl..." button. An ACL is defined with a property called <code>access</code> that refers to an object
that is an array of ACL entries. Each ACL entry has two properties, one is the <code>role</code> that refers to which user
or group that the ACL is valid for, and the <code>permissionLevel</code> which refers to a permission level object (which can
be found in the Object Browser at root/securitySettings/permissionLevelTypes). In addition, an ACL can have
a <code>public</code> that can define the access for anyone that access the system without signing in. The <code>public</code>
should refer to a permission level object. To add ACL entries with the JSPON Object browser, choose the access object
and click "Add list item".</p>
<h3>Groups</h3>
<p>Jsponic provides role/group based security. Groups can be defined and used in ACLs. The easiest way to 
create a group is to go to the <a href="browser.html?id=root">JSPON Object Browser</a> and 
choose the group property and click the "Add list item" button. This will allow you to create a new group.
You can then select the group and click the "Add list item" button again and add new users or groups as 
members of the group.  

</p>
<h2>Incorporating Jsponic with JSEE Applications</h2>
<p>
Jsponic uses a filter
to add persistence and referencing capabilities to Java Servlets. With this capability, clients can go beyond just
passing strings as parameters, but can pass any value and the servlet can access the parameter
values as as Strings, Booleans, Dates, Numbers, Objects, and more. There are two primary ways to utilize this capability:
<ul>
<li><strong>Jsponic Action</strong> - You can implement the JsponicAction abstract class to create a 
Jsponic action. A Jsponic action is a servlet and can be used like other servlets, except with enhanced parameter
value capability and the ability to return a value to the client.
</li>
<li><strong>JsponicRequest and JsponicResponse</strong> - You can build a Servlet as normal, and then
you can cast the ServletRequest and the ServletResponse to JsponicRequest and JsponicResponse to add the
ability to read the parameters as flexible values and return a value to the client. 
</li></ul>
Please see the <a href="javadocs/index.html">Javadocs</a> for more information.
</p>

<h2>Configuring Jsponic</h2>
<h3>Data Sources</h3>
<p>
Jsponic should be ready to use out of the box. However, the main configuration that may be desired is to
setup new data sources. Existing databases or data sources can be exposed through Jsponic. The configuration
is defined in the WEB-INF/classes/DataSources.json. This file contains examples of various data sources
and how to configure them. You may also create new data sources by implementing com.xucia.jsponic.datasource.DataSource.
com.xucia.jsponic.datasource.BaseDataSource provides a good starting abstract implementation for data sources,
and com.xucia.jsponic.datasource.DatabaseTableDataSource provides a good example of database data source.
Please see the <a href="javadocs/index.html">Javadocs</a> for more information.
</p>
<h3>Server Side Scripts</h3>
<p>
Jsponic may be configured to include server scripts in the server JavaScript environment. A JavaScript library
may be included in the server environment by adding to the serverScripts array in the DataSources.json configuration file.</p>
<h2>Custom Model Objects</h2>
<p>
Jsponic allows you to create custom classes as model objects. This allows you to write
custom Java model objects that can provide custom behavior. Model classes should implement
com.xucia.jsponic.data.Persistable which is most easily done by extending org.mozilla.javascript.NativeObject 
or org.mozilla.javascript.NativeArray.
To register a custom class,
a new entry should be added to the root/javaClassBasises list. The new entry should specify
the class name of the custom class. To create new objects that are instance of this
custom class, create objects that are instances of the new entry (in javaClassBasises).
When an object is created with a basis/prototype of your javaClassBasises entry, it will
be an instance of the custom class.
</p>
<h2>License</h2>
<pre>
BEGIN LICENSE BLOCK
Version: MPL 1.1/GPL 2.0/LGPL 2.1

The contents of this file are subject to the Mozilla Public License Version
1.1 (the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.mozilla.org/MPL/

Software distributed under the License is distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
for the specific language governing rights and limitations under the
License.
END LICENSE BLOCK
</pre>
<h2>Notes</h2>
<p>
Jsponic is still in alpha, so there will still be some API changes before it is fully released.</p>
</body></html>